Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

lib: enable no-std compatibility #95

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Conversation

rmsyn
Copy link

@rmsyn rmsyn commented Jan 28, 2023

Pull Request Overview

Add a default std feature, and use compatible data structures from alloc, core, and core2 for no-std builds.

To build for no-std pass --no-default-features on the command line, or default-features = false in the Cargo.toml of another library/binary using lzma-rs.

Testing Strategy

This pull request was tested by...

  • Added relevant unit tests.
  • Added relevant end-to-end tests (such as .lzma, .lzma2, .xz files).

Building and testing with the new std feature, and with no-default-features.

Cargo.toml Outdated
@@ -16,14 +16,17 @@ byteorder = "1.4.3"
crc = "3.0.0"
log = { version = "0.4.17", optional = true }
env_logger = { version = "0.9.0", optional = true }
core2 = "0.4"
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This crate has not been updated in 2 years and has a "CI failing" badge, so I'm not sure it's a good choice.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe not, I also saw the failing CI. FWIW, they only fail for nightly builds. Not sure what a better choice for io traits in no_std builds would be.

Suggestions?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've opened a pull request to fix CI builds in core2/#21.

Cargo.toml Outdated
enable_logging = ["env_logger", "log"]
stream = []
raw_decoder = []
std = []
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In terms of features, "no_std" should be an opt in, as it pulls an additional crate (core2). This crate should be optional, and only pulled for users who explicitly opt into the "no_std" feature.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can change this. Makes sense to do opt-in for pulling in optional dependency crates.

Add opt-in `no_std` feature, and use compatible data structures from
`alloc`, `core`, and `core2` for `no-std` builds.

To build for `no-std` pass `--features no_std` on the command line,
or `features = ["no_std"]` in a Cargo.toml using `lzma-rs`.
@@ -25,6 +26,7 @@ seq-macro = "0.3"
enable_logging = ["env_logger", "log"]
stream = []
raw_decoder = []
no_std = ["core2"]

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is 100% opposite of what is suggested in the cargo book:

"features should be additive. That is, enabling a feature should not disable functionality, and it should usually be safe to enable any combination of features. A feature should not introduce a SemVer-incompatible change.

For example, if you want to optionally support no_std environments, do not use a no_std feature. Instead, use a std feature that enables std."

In my experience, people are definitely following the cargo book's recommendation. So I think you had it right the first time.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the review.

Instead, use a std feature that enables std

I think this advice is for the general case, when optional dependencies aren't involved. It's not possible to use optional dependencies in a no_std build using the std feature approach.

This is one of the main reasons @gendx suggested using the no_std feature approach.

Reverting to the original PR isn't much work, but the changes do have their drawbacks.

A feature should not introduce a SemVer-incompatible change.

This PR (both versions) do not break SemVer, users would still get std builds by default. Compiled code should literally be identical to code without the changes, unless the opt-in feature is used.

In the original, the user opts-in with --default-features false. In the current version, the user opts-in with --features no_std. Otherwise, the build should use all the std dependencies, and be identical to the current mainline.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

std should be part of your defaults, people who want to use it with no_std will use --default-features false (or default-features = false in the Cargo.toml). This is the pattern that exists across all the crates I work with in the embedded space.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

std should be part of your defaults, people who want to use it with no_std will use --default-features false (or default-features = false in the Cargo.toml). This is the pattern that exists across all the crates I work with in the embedded space.

I agree with you, that's why I did it that way in the original PR. The (now-)optional dependency gets dropped from compilation when std feature is enabled, since it's not used anywhere else. That essentially turns a required dependency into an optional dependency, with the exception that the crate (and its dependencies) are always downloaded.

I'm fine with either version, honestly. I can revert to the original changes, or keep the PR as it is now. It's up to what @gendx wants to do.

Still no movement on the core2 PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants